package com.appistry.storage;

import java.io.InputStream;
import java.util.List;

import com.appistry.storage.exception.StorageManagerException;

public interface File {
	/**
	 * Returns the metadata info for this file
	 * 
	 * @return
	 * @throws StorageManagerException
	 */
	public FileMetaData getFileMetaData() throws StorageManagerException;
	
	/**
	 * Refreshes the metadata for this file
	 * 
	 * @return
	 * @throws StorageManagerException
	 */
	public FileMetaData refreshFileMetaData() throws StorageManagerException;

	/**
	 * Returns a list of ips where this file is located.
	 * 
	 * @return
	 */
	public List<String> getIps() throws StorageManagerException;

	/**
	 * Returns a list of ips and port where this file is located.
	 * 
	 * @return
	 */
	public List<String> getLocations() throws StorageManagerException;

	/**
	 * Returns the filename.
	 * 
	 * <br>
	 * <br>
	 * <i>Example:</i><br>
	 * File: /usr/local/filename.dat<br>
	 * Return: filename.dat
	 * 
	 * @return
	 */
	public String getName();

	/**
	 * Returns the full pathname including filename.
	 * 
	 * <br>
	 * <br>
	 * <i>Example:</i><br>
	 * File: /usr/local/filename.dat<br>
	 * Return: /usr/local/filename.dat
	 * 
	 * @return
	 */
	public String getPath();

	/**
	 * Returns the directory this file resides in.
	 * 
	 * <br>
	 * <br>
	 * <i>Example:</i><br>
	 * File: /usr/local/filename.dat<br>
	 * Return: /usr/local
	 * 
	 * @return
	 */
	public String getParent();
	
	/**
	 * Returns true if the file path returned is a directory.
	 * @return
	 */
	public boolean isDir();

	/**
	 * Retreives the file returning the bytes via an InputStream
	 * 
	 * @return
	 * @throws StorageManagerException
	 */
	public InputStream getFile() throws StorageManagerException;

	/**
	 * Retreives the file returning the bytes via an InputStream 
	 * with a minimum number of copies read.
	 * 
	 * @param minReadCopies The minimum copies of the file compared in a successful read operation.
	 * @return
	 * @throws StorageManagerException
	 */
	public InputStream getFile(int minReadCopies) throws StorageManagerException;

	/**
	 * Retreives the file returning the bytes via an InputStream 
	 * with a specified version.
	 *  
	 * @param version A specific version of a file stored in the system
	 * @return
	 * @throws StorageManagerException
	 */
	public InputStream getFile(String version) throws StorageManagerException;

	/**
	 * Retreives the file returning the bytes via an InputStream 
	 * with a minimum number of copies read, the offset, and how much to read.
	 * 
	 * @param minReadCopies The minimum copies of the file compared in a successful read operation.
	 * @param offset Specifies how many bytes into the file to begin reading. Default value is 0 (the beginning of the file).
	 * @param length Specifies how many bytes of the file to read. Default value is from the 'offset' to the end of the file.
	 * @return
	 * @throws StorageManagerException
	 */
	public InputStream getFile(int minReadCopies, long offset, long length) throws StorageManagerException;

	/**
	 * Retreives the file returning the bytes via an InputStream 
	 * from a specified offset and up to a specified length.
	 * 
	 * @param offset Specifies how many bytes into the file to begin reading. Default value is 0 (the beginning of the file).
	 * @param length Specifies how many bytes of the file to read. Default value is from the 'offset' to the end of the file.
	 * @return
	 * @throws StorageManagerException
	 */
	public InputStream getFile(long offset, long length) throws StorageManagerException;

	/**
 	 * Retreives the file returning the bytes via an InputStream 
	 * from a specified version and a minimum number of copies read.
	 * 
	 * @param version A specific version of a file stored in the system
	 * @param minReadCopies The minimum copies of the file compared in a successful read operation.
	 * @return
	 * @throws StorageManagerException
	 */
	public InputStream getFile(String version, int minReadCopies) throws StorageManagerException;

	/**
 	 * Retreives the file returning the bytes via an InputStream 
	 * from a specified version, minimum number of copies read, a specified offset, and up to a specific length.
	 * 
	 * @param version A specific version of a file stored in the system
	 * @param minReadCopies The minimum copies of the file compared in a successful read operation.
	 * @param offset Specifies how many bytes into the file to begin reading. Default value is 0 (the beginning of the file).
	 * @param length Specifies how many bytes of the file to read. Default value is from the 'offset' to the end of the file.
	 * @return
	 * @throws StorageManagerException
	 */
	public InputStream getFile(String version, int minReadCopies, long offset, long length) throws StorageManagerException;

	/**
	 * Writes a file to this location
	 * 
	 * @param content
	 * @throws StorageManagerException
	 */
	public void putFile(InputStream content) throws StorageManagerException;

	/**
	 * Writes a file to this location
	 * 
	 * @param content
	 * @param copies The desired numbered of copies to be maintained in system.
	 * @param minCopies The minimum copies of the file required to be written in a successful write operation.
	 * @param minReadCopies The minimum copies of the file compared in a successful read operation.
	 * @throws StorageManagerException
	 */
	public void putFile(InputStream content, int copies, int minCopies, int minReadCopies) throws StorageManagerException;

	/**
	 * Moves the file to the specified location
	 * 
	 * @param fileNameDest
	 * @throws StorageManagerException
	 */
	public void moveFile(String fileNameDest) throws StorageManagerException;

	/**
	 * Deletes this file
	 * 
	 * @throws StorageManagerException
	 */
	public void deleteFile() throws StorageManagerException;

}
